Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/STUTTGART/FROMUTS/PERL/Perl/ReadMeArc

Text File | 1991-12-14 | 15KB | 406 lines

                  Archimedes Perl, Release 1.00 Notes
          -----------------------------------

This port of the Perl language was produced by Paul Moore, July 1990.

I can be reached at:

E-Mail: [e-mail]

Mail:    10, Mulberry Rise
    Firdale Park,
    Northwich,
    Cheshire
    CW8 4UQ

I am interested in hearing from any perl users who have found bugs in
this implementation of perl. Also, if you have any examples of useful
perl scripts, let me know and I will incorporate them into the
"Examples" directory (with due credit, of course).

This port of perl is based on the Unix version of perl, developed and
distributed by Larry Wall (see the Readme file). Unix perl is covered
by the Gnu General Public License (see file Copying), and hence this
port is also so covered. Note that this distribution omits a lot of
Unix specific stuff from the original distribution. If you wish to
obtain a copy of the original (unported) distribution,  send me a
FORMATTED 800k disk and return postage, and I will supply a copy.  Note
that the distribution is archived using David Pilling's !Spark, version
2.0. If you do not have a suitable extract program (!Spark, or one of
the later versions of !SparkPlug), let me know and include an extra
disk, and I will supply !SparkPlug also.

To recompile perl from the sources, you will need a copy of my "Utils"
library of C routines. This is available from most Archimedes BBSs, or
the Newcastle server, or (if you are desparate) from me - please send a
formatted disk and return postage. You will also require some way of
processing the grammar in Y.Perl. I use a port of bison (the Gnu version
of Yacc). This is available for the Archimedes from David Pilling, on
one of his disks, or from me.

Please remember - if you want stuff from me, please send enough disks,
and format them in advance. Also, be prepared for a long wait - I am
not very reliable when it comes to distributing software! (If you need
fast service, a good solution is to send large quantities of money,
porsches, or equivalent negotiable goods :-)

This version of perl corresponds to Perl 3.0, patch level 44.

If you are interested in Perl, and have access to Usenet, I would
recommend looking at the comp.lang.perl newsgroup. It has loads of
interesting stuff on perl, and the designer, Larry Wall, is a regular
contributor.

Also available these days is a book on Perl, called "Programming Perl",
in the Nutshell Handbook series, published by O'Reilley & Associates.
Authors, Larry Wall and Randal L. Schwartz.

Archimedes Perl
===============

The Archimedes version of perl is mostly identical to the Unix version.
The documentation comes in three forms. The standard documentation
consists of the troff sources for the reference manual, and is in the
four files Perl_man,{1-4}. Also, there is the directory Tex, which
contains TeX sources for further documentation. There is RefCard, which
is a "Reference Card" for perl (patch level 18, I think), and PerlMan,
which is a version of the full perl manual in Gnu "Texinfo" format.
This is available via FTP from chem.bu.edu, in directory
pub/perl-manual. The version here is the latest I have available
(currently, corresponding to patch level 41). For the latter, you need
texinfo version 2.10 (from the latest Gnu Emacs) - you may need to
fiddle with the file if you are using an earlier version of texinfo.

I shall only describe the differences between the standard and
Archimedes versions of Perl here.

As perl is a general purpose language, with low-level access to system
functions, it is clearly the low-level stuff that is the least portable,
and hence which has been altered most radically.


Omitted from Archimedes perl
----------------------------

All Unix OS access functions. Namely,

chmod    chown    link    lstat    select    utime    symlink    readlink
binmode    fcntl    fileno    flock    ioctl    pipe    chroot    fork
alarm    times    umask    wait    accept    bind    connect

getpeername    getsockname    getsockopt    listen
recv        send        setsockopt    shutdown
socket        socketpair    dump        endpwent
getpwent    getpwnam    getpwuid    setpwent
endgrent    getgrgid    getgrnam    getgrent
setgrent    endhostent    gethostbyname    gethostent
sethostent    endnetent    getnetbyaddr    getnetbyname
getnetent    setnetent    endservent    getservbyname
getservbyport    getservent    setservent    endprotoent
getprotobyname    getprotoent    setprotoent    getprotobynumber
getlogin    getpgrp        getppid        getpriority
setpgrp        setpriority

These are not implemented, as there is no Archimedes equivalent.

The facility to duplicate a file descriptor, as open(OLDFD,">&FD")
is not supported. An attempt has been made to support duplicating
STDIN/OUT/ERR, but this does not work reliably, and should not be used.
I will attempt to rectify this problem, but RISC OS does not supply a
dup() system call, so any solution will be dodgy at best.

Also missing, are the "special variables"

$$    The process ID of the current perl process
$< $>    Real and effective User ID
$( $)    Real and effective Group ID

The following "special variables" have been added

$<    The full pathname of the directory where we started perl
$>    The full pathname of the current directory

These were added as there is no "pwd" command on the Archimedes. The
mnemonics in the manual ($< is "where we came from" and $> is "where we
have gone to") are still appropriate.

The variable $! does not correspond to errno in Archimedes perl, as
errno very rarely has a useful value. Instead, the last error from the
kernel (_kernel_last_oserror) is stored in $! whenever an OS call
returns an error (eg, opening files, deleting files, creating
directories, syscall(), etc). The dual nature of $! (returning the
error number in a numeric context, and the error message in a string
context) is retained.

Also missing are the 'N' and 'n' templates from pack/unpack.


File tests in Archimedes perl
-----------------------------

The file tests

-x, -o, -X, -O        File is executable or owned
-l, -S, -p, -b, -c    Special file types
-u, -g, -k        Setuid, setgid, and "sticky"
-M, -C            File time stamps

are missing.

The following have changed meaning

-r            File is readable
-w            File is writeable
-R            File is PUBLICLY readable
-W            File is PUBLICLY writeable
-A            File time stamp ("age")

(See the Archimedes manuals for the distinction here - unless you are
using econet, -R and -W are not very useful). Note that RISC OS only
records one time stamp for a file - this is tested using -A.

New file test

-L            File is locked

Also, the tests -B and -T are NOT defined on filehandles. Only on file
names.


Other changes in Archimedes perl
--------------------------------

The return value from the stat() function has changed. Be careful of
this one when porting Unix perl scripts. The new value is an array of 8
elements, as follows

    Index        Value

    0        Basic file type (r0 on return from OS_File)
    1        File type for timestamped files
    2        Load address
    3        Execution address
    4        File length
    5        File attributes
    6        File timestamp (as centisec past 00:00:00 1/1/1900)
    7        File timestamp (as seconds past 00:00:00 1/1/1970)

Note: Index 0 is 0 for "file not found", 1 for a normal file, and 2 for
a directory. Index 5 is a bit set encoding the read/write/locked status
of the file (see the Archimedes manuals for more details). Indexes 6 and
7 are the same value, in two different forms. The first is the
Archimedes standard "5-byte" time format (all numbers in perl are C
doubles, so there is no loss of precision), and the second is the Unix
standard format.

The mkdir() function does not need a second argument (the file mode,
under Unix). Instead, it is a unary operator, like rmdir - for example,

    mkdir "C";        # Make directory C
    mkdir("Test");        # Make directory Test

Similarly, the syntax of kill() has changed - it takes a single argument
which is a signal number or name, and raises that signal. There is no
list of process IDs - for example,

    kill "INT";        # signal ESCAPE
    kill(4);        # also signal ESCAPE (SIGINT is 4)

These latter two, particularly mkdir(), are a nuisance when porting, and
can cause subtle bugs. I was undecided for a long time as to whether to
preserve portability at the expense of a "natural" look to Archimedes
users. Finally, however, I decided that I prefer the non-portable, but
more natural, form.

There are two new pack/unpack template values. These are to make
conversion of Archimedes standard times easier.

    T    This takes the next 5 bytes of the string, and converts
        it to a number as if it were a 5-byte 2's complement
        integer. This is a suitable conversion if the target
        string was an Archimedes 5-byte time. A repeat count
        converts a series of 5-byte numbers.

    P    This treats the next 4 bytes of the target string as a
        pointer to a string whose length is given in the repeat
        count.  When unpacking, Pn reads EXACTLY n bytes from the
        string pointed to, into the destination string. This is
        unlike p1, which will stop at a NULL.  As there is no way
        of ensuring in pack() that the argument is exactly n
        bytes long, the P template is not accepted in pack().

For example, if $ptr holds a pointer to a 5-byte time (say, from a SWI
call), then

    $time = unpack('P5', $ptr);
    $time = unpack('T',$time);

will get the time value into $time.


"File globbing", such as <C.*>, IS supported, but the filename patterns
conform to the normal Archimedes standard (* is any number of
characters, including 0, and # is any single character). This construct
currently requires the program "Glob" to be available in Run$Path. The
source for Glob is supplied with perl.


Things which DO exist in Archimedes perl
----------------------------------------

The following is a list of things which do exist in Archimedes perl.
They are all documented for Unix perl, but are worth mentioning here,
because they are slightly less "obvious".


1. Unix names for familiar functions.

The following functions exist, and work as expected. The Unix-style
names have been retained for compatibility.

    mkdir        *Cdir
    rmdir        *Delete on a directory
    chdir        *Dir
    unlink        *Remove


2. "Standard" facilities unfamiliar on the Archimedes.

Pipes have been implemented in Archimedes perl. They are implemented
using temporary files, which are put into the directory <Tmp$Dir>, or
&.Tmp, or the current directory, whichever of these exists (they are
tried in that order).

This means that the following perl facilities DO exist

* Opening pipes, as open(FH, "Command|") or open(FH, "|Command").
* The 'backtick' operator, `Command`.

Note that commands can do IO redirection in one of two forms. The
"built-in" OS commands use the standard "Command { < infile > outfile }"
form, with a bit of post-processing to convert CR/NL line terminators
to NL. Other commands are assumed to support the C v3.0 redirection
format, "Command < infile > outfile". Any command which is not built-in
and yet does not allow C redirection, can be forced to use OS
redirection by adding an initial '%' (which is skipped when executing
the command). So, for example, the Acorn utility LibFile, which does
not use C redirection, can be opened as a pipe via

    open(LIB, "%LibFile Lib -l |")


Associating databases with associative arrays. This has been implemented
using the public domain Gnu dbm package. Unfortunately, while this
works, it is presently VERY slow. I am aiming to improve this, but for
now I really only see it as being present for completeness' sake.


The %SIG associative array works as documented, and can be used to trap
Escape, by assigning to $SIG{'INT'}.


3. The syscall() function.

Syscall() has been implemented, and gives access to SWI calls. See the
file Termio in the Perl library (Lib.Termio) for an example of its use.

The calling sequence for syscall() is

    $regs = syscall(SWI, $r0, $r1, ..., $r9);

Here, SWI is the SWI name or number (a string is looked up as a name,
and a number is used directly). $r0 ... $r9 are passed to the registers
to the SWI call. Only as many as are used need be passed. If $rn is a
string, it is passed as a pointer to a 0-terminated string, otherwise it
is passed as a number.

The result, $regs, is either the null string (if an error occurred,
when $! gives the error number/message), or it is a packed string
containing the return values of r0-r9. To get the actual registers,
simply do

    ($r0, $r1, ..., $r9) = unpack('I9', $regs);

Clearly, in the normal case, a more specific unpack() template would be
suitable.

Note that, due to Perl's tendency to treat numbers and strings as
interchangeable, some care must be taken with parameters. For example,

    syscall("OS_Write0",$str);

can fail, if $str is assigned the string "0" - which may have been
converted to numeric zero - as in this case Perl will assume you are
passing a number, and set r0 to 0 instead of the address of the
supplied string "0". To avoid this, make an explicit string - for
example

    syscall("OS_Write0", $str . '');

is guaranteed to work. This is fairly obscure magic (deliberately
invalidating the flag which says that the string has a valid numeric
value, and then using the string before perl has a chance to notice that
the numeric value is still OK), but works fine.

User subroutines
================

Using the "user supplied subroutine" facility, the following functions
and variables are available in all Archimedes perl scripts.

$Mode            The current screen mode. This can be set.
$Rows            The number of screen rows available.
$Cols            The number of screen columns available.

&osrdch()        A single character string, read via OS_ReadC.

&oswrch($ch)        Writes the character $ch (an integer, which is the
            ASCII code) using OS_WriteC. Returns 1 for success,
            undef for failure.

&osrdstr($len,$lo,$hi)    Reads a string using OS_ReadLine. Uses an internal
            buffer, $len characters long, to hold the input.
            $lo and $hi are the lowest and highest ASCII codes
            accepted (defaults 32 and 255 respectively).
            Returns the input buffer.

&oswrstr($str)        Writes $str to the screen. Note that $str may contain
            control characters, including nulls (for example,
            &oswrstr("\026\000") changes to mode 0).
            Returns 1 for success, undef for failure.

&fx($op,$x,$y)        Performs an OS_Byte call. Returns an integer
            containing the resulting r1 in its bottom byte,
            the resulting r2 in  its second byte, 1 in its
            third byte if the carry flag is set, otherwise 0,
            and 0 in its top byte.

Wishlist
========

More special file functions. Maybe settype(type,file...),
settime(time,file...), etc. Maybe some more user functions...

Final Note
==========

Any suggestions for improvement to this port will be most gratefully
received (particularly if they include the changes to the code!) I have
found perl to be extremely useful for "simple" data manipulating tasks.
See, for example, script NL in the Examples directory, which greatly
aids the conversion of files from MS-DOS.

It is possible to make perl scripts executable by allocating a file
type, and putting in your !Boot application (if you have a hard disk),

    *Set Alias$@RunType_xxx Perl %%0 %%*1
    *Set File$Type_xxx Perl

The only thing this doesn't do is support command options which are
always required, such as -P (preprocess using CC -E). But I don't use
this much, anyway.

Have fun with perl!

Paul Moore.